<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Source Links</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Source Links' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../services.html">Services</a></li><li><a href="index.html">html</a></li><li><a href="index.html#2">Chapter 2: Intranet</a></li><li><b>Source Links</b></li></ul></div>
<p class="purpose">To provide HTML links to an Inform source text, using the non-standard "source" protocol.</p>

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. </b>Index and Problem pages generated by <a href="../inform7/index.html" class="internal">inform7</a>, via the <a href="../index-module/index.html" class="internal">index</a> and
<a href="../problems-module/index.html" class="internal">problems</a> modules, frequently need to have clickable icons linking to
positions in the source text; when these are clicked in the Inform UI
applications, the Source panel opens at the appropriate line.
</p>

<p class="commentary">This is done with a non-standard HTML protocol called <span class="extract"><span class="extract-syntax">source:</span></span>, one of
two which the Inform UI apps must provide special handling for. For instance,
line 21 of file <span class="extract"><span class="extract-syntax">Bits and Pieces/marbles.txt</span></span> has URL:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">source:Bits</span><span class="plain-syntax"> </span><span class="identifier-syntax">and</span><span class="plain-syntax"> </span><span class="identifier-syntax">Pieces</span><span class="plain-syntax">/</span><span class="identifier-syntax">marbles</span><span class="plain-syntax">.</span><span class="identifier-syntax">txt</span><span class="plain-syntax">#</span><span class="identifier-syntax">line14</span>
</pre>
<p class="commentary">When an Inform app is viewing an extension project, there can also be
references to individual examples in that extension, and these are referred
to as "cases" since they are test cases when the app is testing the extension.
For example,
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">source:Locksmith</span><span class="plain-syntax">.</span><span class="identifier-syntax">i7x</span><span class="plain-syntax">?</span><span class="reserved-syntax">case</span><span class="plain-syntax">=</span><span class="identifier-syntax">B</span><span class="plain-syntax">#</span><span class="identifier-syntax">line7</span>
</pre>
<p class="commentary">refers to line 7 of Example B of <span class="extract"><span class="extract-syntax">Locksmith.i7x</span></span>.
</p>

<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>Locations are given relative to the current project bundle. However, if
only a leafname is supplied, then this is read as a file within the <span class="extract"><span class="extract-syntax">Source</span></span>
subfolder of the project bundle. (Thus it is not possible to have a
source link to a source file at the root of the project bundle: but this is
no loss, since source is not allowed to be kept there.) For instance,
line 14 of file <span class="extract"><span class="extract-syntax">Source/story.ni</span></span> has URL
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">source:story</span><span class="plain-syntax">.</span><span class="identifier-syntax">ni</span><span class="plain-syntax">#</span><span class="identifier-syntax">line14</span>
</pre>
<p class="commentary">The following routine writes the clickable source-reference icon, and
is the only place in Inform where <span class="extract"><span class="extract-syntax">source:</span></span> URLs are generated.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">inchar32_t</span><span class="plain-syntax"> </span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceLinks::set_case</span><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">p</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Characters::toupper</span><span class="plain-syntax">(</span><span class="identifier-syntax">Str::get_first_char</span><span class="plain-syntax">(</span><span class="identifier-syntax">p</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">SourceLinks::link</span><span class="plain-syntax">(</span><span class="identifier-syntax">OUTPUT_STREAM</span><span class="plain-syntax">, </span><span class="identifier-syntax">source_location</span><span class="plain-syntax"> </span><span class="identifier-syntax">sl</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">nonbreaking_space</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="string-syntax">"%f"</span><span class="plain-syntax">, </span><span class="identifier-syntax">TextFromFiles::get_filename</span><span class="plain-syntax">(</span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">file_of_origin</span><span class="plain-syntax">));</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="2-sl.html#SP2_1" class="named-paragraph-link"><span class="named-paragraph">Truncate the path according to the current abbreviation</span><span class="named-paragraph-number">2.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="2-sl.html#SP2_2" class="named-paragraph-link"><span class="named-paragraph">Remove indication that the path is inside the Source directory</span><span class="named-paragraph-number">2.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">nonbreaking_space</span><span class="plain-syntax">) </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">"&amp;nbsp;"</span><span class="plain-syntax">); </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">WRITE</span><span class="plain-syntax">(</span><span class="string-syntax">" "</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"a"</span><span class="plain-syntax">, </span><span class="string-syntax">"href=\"source:%S?case=%c#line%d\""</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">source_link_case</span><span class="plain-syntax">, </span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">line_number</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">else</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">HTML_OPEN_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"a"</span><span class="plain-syntax">, </span><span class="string-syntax">"href=\"source:%S#line%d\""</span><span class="plain-syntax">, </span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">sl</span><span class="plain-syntax">.</span><span class="identifier-syntax">line_number</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">HTML_TAG_WITH</span><span class="plain-syntax">(</span><span class="string-syntax">"img"</span><span class="plain-syntax">, </span><span class="string-syntax">"border=0 src=inform:/doc_images/Reveal.png"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">HTML_CLOSE</span><span class="plain-syntax">(</span><span class="string-syntax">"a"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">)</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP2_1" class="paragraph-anchor"></a><b>&#167;2.1. </b>This rather clumsily simplifies links to make them relative.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Truncate the path according to the current abbreviation</span><span class="named-paragraph-number">2.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">abbrev</span><span class="plain-syntax"> = </span><span class="identifier-syntax">HTML::get_link_abbreviation_path</span><span class="plain-syntax">();</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">abbrev</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">, </span><span class="string-syntax">"%p"</span><span class="plain-syntax">, </span><span class="identifier-syntax">abbrev</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::prefix_eq</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">pp</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">)) </span><span class="identifier-syntax">Str::delete_n_characters</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">+1);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">pp</span><span class="plain-syntax">)</span>
<span class="plain-syntax">    }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="2-sl.html#SP2">&#167;2</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP2_2" class="paragraph-anchor"></a><b>&#167;2.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Remove indication that the path is inside the Source directory</span><span class="named-paragraph-number">2.2</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::begins_with_wide_string</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="identifier-syntax">U</span><span class="string-syntax">"Source"</span><span class="plain-syntax">)) &amp;&amp;</span>
<span class="plain-syntax">        (</span><span class="identifier-syntax">Platform::is_folder_separator</span><span class="plain-syntax">(</span><span class="identifier-syntax">Str::get_at</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="constant-syntax">6</span><span class="plain-syntax">))))</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">Str::delete_n_characters</span><span class="plain-syntax">(</span><span class="identifier-syntax">fn</span><span class="plain-syntax">, </span><span class="constant-syntax">7</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="2-sl.html#SP2">&#167;2</a>.</li></ul>
<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="2-ip.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresschapter"><a href="1-hm.html">1</a></li><li class="progresscurrentchapter">2</li><li class="progresssection"><a href="2-ip.html">ip</a></li><li class="progresscurrent">sl</li><li class="progresssection"><a href="2-pb.html">pb</a></li><li class="progresssection"><a href="2-if.html">if</a></li><li class="progresssection"><a href="2-dr.html">dr</a></li><li class="progresssection"><a href="2-lcl.html">lcl</a></li><li class="progressnext"><a href="2-pb.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

